// SAX for Pascal, Simple API for XML Extension Interfaces in Pascal.
// http://sourceforge.net/projects/saxforpascal/
// No warranty; no copyright -- use this as you will.
unit SFP;

interface

uses
  SAX;

const

  // SAX for Pascal feature names
  SFPFeatures           = 'http://saxforpascal.org/features/';
  ReaderControlFeature  = SAXString(SFPFeatures + 'use-reader-control');

  // IXMLReaderControl does not use SAXStrings, no need for separate GUIDs
  IID_IXMLReaderControl = '{36EDFFE1-28B0-42AE-B319-6A603E1B55AB}';

type

  IXMLReaderControl = interface;

  // SAX2 extension - proprietary to SAX for Pascal (as of Nov. 2003).
  // It allows suspending and resuming the processing of an XML document
  // efficiently, without the use of multiple threads.
  // If an implementation supports this extension, the XMLReader will
  // implement this interface, and the
  // <em>http://saxforpascal.org/features/use-reader-control</em> feature
  // flag will have the value <em>true</em>.
  //
  // <blockquote>
  // <em>This module, both source code and documentation, is in the
  // Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  // </blockquote>
  //
  // <p> XMLReader implementations are not required to implement this
  // capability, and it is not part of core-only SAX2 distributions.</p>
  //
  // <p>If an implementation supports IXMLReaderControl, it is only
  // required to support its functionality for content related call-backs
  // (IContentHandler, ILexicalHandler), but not for DTD related events
  // (IDTDHandler, IDeclHandler, ILexicalHandler).</p>
  //
  // <p>An implementation may decide to suspend/abort parsing not
  // immediately, but rather "as soon as possible". This can for instance
  // mean that, after calling suspend()/abort() in the startElement() call-back
  // of an empty element tag, the endElement() call-back may still follow.</p>
  //
  // <p>This capability allows one to turn a SAX parser into a Pull parser
  // when a suitable implementation of IContentHandler is used that calls
  // IXMLReaderControl.suspend() whenever an event of interest occurs.</p>
  //
  // @since SAX for Pascal 1.2
  TXMLReaderStatus = (xrsReady, xrsParsing, xrsSuspended);
  IXMLReaderControl = interface(IUnknown)
    [IID_IXMLReaderControl]
    // Causes the XMLReader to return from parsing in such a way that
    // parsing can be resumed again calling IXMLReader.resume().
    //
    // It is only legal to call suspend() when Status = xrsParsing, and
    // this should only be done from within a handler-callback, otherwise
    // an exception derived from ESAXException will be raised.
    // On return, the Status property will have the value xrsSuspended.
    procedure suspend();
    // Causes the parser to stop parsing with a fatal error. It will not
    // be possible to resume parsing with resume() again.
    //
    // It is legal to call this from within a handler call-back, that is,
    // when Status = xrsParsing, or from anywhere when parsing is suspended
    // (Status = xrsSuspended). Otherwise, an exception derived from
    // ESAXException will be raised.
    // The Status property will have the value xrsReady, once parse() or
    // resume() have returned.
    procedure abort();
    // Resumes parsing as if IXMLReader.parse() continued with the same
    // input source it was originally called with.
    //
    // It is only legal to call resume() when parsing is suspended, that is,
    // when Status = xrsSuspended, otherwise an exception derived from
    // ESAXException will be raised.
    // The Status property will have the value xrsParsing immediately
    // afterwards (in the next handler-callback), but on return the
    // value will be xrsReady - when parsing is done - or xrsSuspended.
    procedure resume();
    // Returns the parsing status of the XMLReader.
    // The possible values are:
    // xrsReady     ... parser initialized - ready to parse (again)
    // xrsParsing   ... parsing is under way - should only be detectable
    //                  from within a call-back handler
    // xrsSuspended ... parsing of XML input source is suspended - but not
    //                  completed yet - and it can be resumed later
    function getStatus(): TXMLReaderStatus;
    property Status: TXMLReaderStatus read getStatus;
  end;


implementation

end.
